<!DOCTYPE html>
<html prefix="og: http://ogp.me/ns#">
<head>
  <meta charset="UTF-8">
  <title>Serialization in Atom</title>
  <link data-turbolinks-track="true" href="../../../assets/application-b86a2086c99917c6bf2a9d74b4038381.css" media="all" rel="stylesheet" />
  <script data-turbolinks-track="true" src="../../../assets/application-c3106c6fe52ccec6f26495730a478cca.js"></script>
  <meta content="authenticity_token" name="csrf-param" />
<meta content="yzXUiWH6GiCHbvbJOg7usjzA7LawyxwB+oJHEcWTOIM=" name="csrf-token" />
  <script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','//www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-3769691-35', 'atom.io');
  ga('send', 'pageview');

</script>

  <meta property="og:url" content="https://atom.io/" />
<meta property="og:site_name" content="Atom" />
<meta property="og:title" content="A hackable text editor for the 21st Century" />
<meta property="og:description" content="At GitHub, we’re building the text editor we’ve always wanted: hackable to the core, but approachable on the first day without ever touching a config file. We can’t wait to see what you build with it." />
<meta property="og:type" content="website" />
<meta property="og:author" content='https://www.facebook.com/GitHub' />
<meta property="og:image" content="http://og.github.com/atom-logo/atom-logo@1200x1200.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="1200" />
<meta property="og:image" content="http://og.github.com/atom-mark/atom-mark@1200x630.png" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />

  <meta property="twitter:card" content="summary_large_image" />
<meta property="twitter:site" content="@AtomEditor" />
<meta property="twitter:creator" content='@github' />
<meta property="twitter:title" content="Atom" />
<meta property="twitter:description" content="A hackable text editor for the 21st Century" />
<meta property="twitter:image:src" content="http://og.github.com/atom-logo/atom-logo@1200x630.png" />
<meta property="twitter:image:width" content="1200" />
<meta property="twitter:image:height" content="630" />

  <link rel="shortcut icon" href="../../../favicon.ico"/>
</head>
<body>

  <div class="footer-push">
    
    

    <header class="header">
  <div class="wrapper">
    <h1 title="Atom">
      <a href="../../../index.html" class="logo"></a>
    </h1>

    <ul class="navigation">
      <li><a class="" href="../../../packages.html">Packages</a></li>
      <li><a class="is-selected" href="../../latest/index.html">Documentation</a></li>
      <li><a href="http://blog.atom.io">Blog</a></li>
      <li><a href="../../../faq.html">FAQ</a></li>
      <li><a class="" href="https://atom.io/contact">Contact</a></li>
    </ul>
  </div>
</header>


    <div class="wrapper documents content-push">
  <div class="columns">
    <div class="column main-column markdown">
        <h2>
<a name="serialization-in-atom" href="serialization.html#serialization-in-atom"></a>Serialization in Atom</h2>

<p>When a window is refreshed or restored from a previous session, the view and its
associated objects are <em>deserialized</em> from a JSON representation that was stored
during the window's previous shutdown. For your own views and objects to be
compatible with refreshing, you'll need to make them play nicely with the
serializing and deserializing.</p>

<h3>
<a name="package-serialization-hook" href="serialization.html#package-serialization-hook"></a>Package Serialization Hook</h3>

<p>Your package's main module can optionally include a <code>serialize</code> method, which
will be called before your package is deactivated. You should return JSON, which
will be handed back to you as an argument to <code>activate</code> next time it is called.
In the following example, the package keeps an instance of <code>MyObject</code> in the
same state across refreshes.</p>

<pre lang="coffee-script"><div class="line"><span class="source coffee"><span class="variable assignment coffee"><span class="variable assignment coffee"><span>module.exports </span><span class="keyword operator coffee"><span>=</span></span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>activat</span><span class="entity name function coffee"><span>e</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="meta inline function coffee"><span class="variable parameter function coffee"><span>(state)</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="variable other readwrite instance coffee"><span>@myObject</span></span><span> </span><span class="keyword operator coffee"><span>=</span></span></span></div><div class="line"><span class="source coffee"><span>      </span><span class="keyword control coffee"><span>if</span></span><span> state</span></span></div><div class="line"><span class="source coffee"><span>        deserialize</span><span class="meta brace round coffee"><span>(</span></span><span>state</span><span class="meta brace round coffee"><span>)</span></span></span></div><div class="line"><span class="source coffee"><span>      </span><span class="keyword control coffee"><span>else</span></span></span></div><div class="line"><span class="source coffee"><span>        </span><span class="meta class instance constructor"><span class="keyword operator new coffee"><span>new</span></span><span> </span><span class="entity name type instance coffee"><span>MyObject</span></span></span><span class="meta brace round coffee"><span>(</span></span><span class="string quoted double coffee"><span class="punctuation definition string begin coffee"><span>"</span></span><span>Hello</span><span class="punctuation definition string end coffee"><span>"</span></span></span><span class="meta brace round coffee"><span>)</span></span></span></div><div class="line"><span class="source coffee"><span> </span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>serializ</span><span class="entity name function coffee"><span>e</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span></div><div class="line"><span class="source coffee"><span>    </span><span class="variable other readwrite instance coffee"><span>@myObject</span></span><span class="meta delimiter method period coffee"><span>.</span></span><span>serialize</span><span class="meta brace round coffee"><span>(</span><span>)</span></span></span></div></pre>

<h3>
<a name="serialization-methods" href="serialization.html#serialization-methods"></a>Serialization Methods</h3>

<pre lang="coffee-script"><div class="line"><span class="source coffee"><span class="meta class coffee"><span class="storage type class coffee"><span>class</span></span><span> </span><span class="entity name type class coffee"><span>MyObject</span></span></span></span></div><div class="line"><span class="source coffee"><span>  registerDeserializer</span><span class="meta brace round coffee"><span>(</span></span><span class="variable language coffee"><span>this</span></span><span class="meta brace round coffee"><span>)</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>@deserializ</span><span class="entity name function coffee"><span>e</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="meta inline function coffee"><span class="variable parameter function coffee"><span>({data})</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span><span> </span><span class="meta class instance constructor"><span class="keyword operator new coffee"><span>new</span></span><span> </span><span class="entity name type instance coffee"><span>MyObject</span></span></span><span class="meta brace round coffee"><span>(</span></span><span>data</span><span class="meta brace round coffee"><span>)</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>constructo</span><span class="entity name function coffee"><span>r</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="meta inline function coffee"><span class="variable parameter function coffee"><span>(@data)</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>serializ</span><span class="entity name function coffee"><span>e</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span><span> </span><span class="meta brace curly coffee"><span>{</span></span><span> </span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>deserializer</span><span class="punctuation separator key-value"><span>:</span></span></span></span><span> </span><span class="string quoted single coffee"><span class="punctuation definition string begin coffee"><span>'</span></span><span>MyObject</span><span class="punctuation definition string end coffee"><span>'</span></span></span><span class="meta delimiter object comma coffee"><span>, </span></span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>data</span><span class="punctuation separator key-value"><span>:</span></span></span></span><span> </span><span class="variable other readwrite instance coffee"><span>@data</span></span><span> </span><span class="meta brace curly coffee"><span>}</span></span></span></div></pre>

<h4>
<a name="serialize" href="serialization.html#serialize"></a>.serialize()</h4>

<p>Objects that you want to serialize should implement <code>.serialize()</code>. This method
should return a serializable object, and it must contain a key named
<code>deserializer</code> whose value is the name of a registered deserializer that can
convert the rest of the data to an object. It's usually just the name of the
class itself.</p>

<h4>
<a name="deserializedata" href="serialization.html#deserializedata"></a>@deserialize(data)</h4>

<p>The other side of the coin is the <code>deserialize</code> method, which is usually a
class-level method on the same class that implements <code>serialize</code>. This method's
job is to convert a state object returned from a previous call <code>serialize</code> back
into a genuine object.</p>

<h4>
<a name="registerdeserializerklass" href="serialization.html#registerdeserializerklass"></a>registerDeserializer(klass)</h4>

<p>You need to call the global <code>registerDeserializer</code> method with your class in
order to make it available to the deserialization system. Now you can call the
global <code>deserialize</code> method with state returned from <code>serialize</code>, and your
class's <code>deserialize</code> method will be selected automatically.</p>

<h3>
<a name="versioning" href="serialization.html#versioning"></a>Versioning</h3>

<pre lang="coffee-script"><div class="line"><span class="source coffee"><span class="meta class coffee"><span class="storage type class coffee"><span>class</span></span><span> </span><span class="entity name type class coffee"><span>MyObject</span></span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="variable other readwrite instance coffee"><span>@version</span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="constant numeric coffee"><span>2</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>@deserializ</span><span class="entity name function coffee"><span>e</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="meta inline function coffee"><span class="variable parameter function coffee"><span>(state)</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span></span><span> </span><span class="keyword operator coffee"><span>...</span></span></span></div><div class="line"><span class="source coffee"><span>  </span><span class="meta function coffee"><span class="entity name function coffee"><span>serializ</span><span class="entity name function coffee"><span>e</span></span></span></span><span class="keyword operator coffee"><span>:</span></span><span> </span><span class="storage type function coffee"><span>-&gt;</span></span><span> </span><span class="meta brace curly coffee"><span>{</span></span><span> </span><span class="variable assignment coffee"><span class="variable assignment coffee"><span>version</span><span class="punctuation separator key-value"><span>:</span></span></span></span><span> MyObject</span><span class="meta delimiter method period coffee"><span>.</span></span><span>version</span><span class="meta delimiter object comma coffee"><span>, </span></span><span class="keyword operator coffee"><span>...</span></span><span> </span><span class="meta brace curly coffee"><span>}</span></span></span></div></pre>

<p>Your serializable class can optionally have a class-level <code>@version</code> property
and include a <code>version</code> key in its serialized state. When deserializing, Atom
will only attempt to call deserialize if the two versions match, and otherwise
return undefined. We plan on implementing a migration system in the future, but
this at least protects you from improperly deserializing old state. If you find
yourself in dire need of the migration system, let us know.</p>
    </div>
    <div class="column sidebar documents-toc">
      <select class="js-doc-version-switcher version-switcher">
  <option value="v0.69.0">v0.69.0</option>
<option value="v0.68.0">v0.68.0</option>
<option value="v0.67.0">v0.67.0</option>
<option value="v0.66.0">v0.66.0</option>
<option value="v0.65.0">v0.65.0</option>
<option value="v0.64.0">v0.64.0</option>
<option value="v0.63.0">v0.63.0</option>
<option value="v0.62.0">v0.62.0</option>
<option selected="selected" value="v0.61.0">v0.61.0</option>
<option value="v0.60.0">v0.60.0</option>
<option value="v0.59.0">v0.59.0</option>
<option value="v0.58.0">v0.58.0</option>
<option value="v0.57.0">v0.57.0</option>
<option value="v0.56.0">v0.56.0</option>
<option value="v0.55.0">v0.55.0</option>
<option value="v0.54.0">v0.54.0</option>
<option value="v0.53.0">v0.53.0</option>
<option value="v0.51.0">v0.51.0</option>
<option value="v0.50.0">v0.50.0</option>
<option value="v0.49.0">v0.49.0</option>
<option value="v0.48.0">v0.48.0</option>
<option value="v0.47.0">v0.47.0</option>
<option value="v0.46.0">v0.46.0</option>
<option value="v0.45.0">v0.45.0</option>
<option value="v0.44.0">v0.44.0</option>
<option value="v0.41.0">v0.41.0</option>
<option value="v0.40.0">v0.40.0</option>
<option value="0.52.0">0.52.0</option>
</select>


      <ul class="navigation">
        <li><a href="" class="is-selected">Documentation</a></li>
        <li><a href="../../api/v0.61.0/api/index.html">API</a></li>
      </ul>

      <hr />

      <form accept-charset="UTF-8" action="/docs/v0.61.0/search" method="get"><div style="margin:0;padding:0;display:inline"><input name="utf8" type="hidden" value="&#x2713;" /></div>
        <input class="sidebar-search-field" id="q" name="q" placeholder="Search documentation" type="text" value="" />
</form>
      <h2>
<a name="guides" href="serialization.html#guides"></a>Guides</h2>

<ul>
<li><a href="../getting-started.html">Getting Started</a></li>
<li><a href="../customizing-atom.html">Customizing Atom</a></li>
<li><a href="../creating-a-package.html">Creating a Package</a></li>
<li><a href="../creating-a-theme.html">Creating a Theme</a></li>
<li><a href="../publishing-a-package.html">Publishing a Package</a></li>
<li><a href="../converting-a-text-mate-bundle.html">Converting a TextMate Bundle</a></li>
<li><a href="../converting-a-text-mate-theme.html">Converting a TextMate Theme</a></li>
<li><a href="../contributing.html">Contributing</a></li>
</ul><h3>
<a name="advanced-topics" href="serialization.html#advanced-topics"></a>Advanced Topics</h3>

<ul>
<li><a href="configuration.html">Configuration</a></li>
<li><a href="keymaps.html">Keymaps</a></li>
<li><a href="serialization.html">Serialization</a></li>
<li><a href="view-system.html">View System</a></li>
</ul>
    </div>
  </div>
</div>


    <div class="footer-pad"></div>
  </div>

  <footer>
  <div class="footer">
    <div class="wrapper">
      <ul class="footer-left">
        <li><a href="../../../terms.html">Terms of Use</a></li>
          <li><a href="https://atom.io/login">Sign in</a></li>
      </ul>

      <div class="footer-right">
        <a href="https://github.com"><span class="octicon octicon-code"></span> with <span class="octicon octicon-heart"></span> by <span class="octicon octicon-logo-github"></span></a>
      </div>
    </div>
  </div>
</footer>

</body>
</html>
